Transport level retry by l-trotta · Pull Request #954 · elastic/elasticsearch-java

l-trotta · 2025-03-03T17:00:37Z

Adds new retry functionality to the client, configurable like so:

try (ElasticsearchClient client = ElasticsearchClient.of(e -> e
    .host(serverUrl)
    .apiKey(apikey)
    .retryConfig(r -> r
        .backoffPolicy(BackoffPolicy.constantBackoff(5000L,5)) // defaults to BackoffPolicy.noBackoff()
        .retryableExceptions(Set.of(SocketException.class)) // defaults to IOException.class
        .retryableStatuses(429,503) // defaults to 429, 500, 502, 503, 504
    )
))

Or if only a single request needs to be retried:

try (ElasticsearchClient client = ElasticsearchClient.of(e -> e
    .host(serverUrl)
    .apiKey(apikey)
)) {
    client.withTransportOptions(o -> o
        .retryConfig(r -> r
            .backoffPolicy(BackoffPolicy.constantBackoff(5000L,5))
        ))
    .ping();
}

The delegate client (Rest5Client, RestClient or any custom client) is wrapped in an instance of RetryingHttpClient, which takes care of the retrying logic according to the configuration.
This only concerns the same node the request was originally sent to, it's still the underlying client's responsibility to handle dead node logic and node selection.

swallez

Left some comments on implementation independence and async tasks.

Adding this to TransportOptions is an interesting choice, as it allows using different retry policies with a single transport.

Copilot

Pull request overview

This PR introduces transport-level retry support in the Java client by adding a configurable RetryConfig (backoff + retryable statuses/exceptions) and routing requests through a new RetryingHttpClient wrapper when retries are enabled (globally or per-request). It also updates the low-level client adapters so status-carrying exceptions (e.g., ResponseException) can be classified by HTTP status for retry decisions.

Changes:

Add RetryConfig and TransportOptions#retryConfig() to configure retry behavior at the client or request level.
Introduce RetryingHttpClient and integrate it into ElasticsearchTransportBase with lazy, shared wrapping.
Add/extend tests to validate retry behavior (status-based, exception-based, cancellation) across mocked and real HTTP clients.

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
java-client/src/test/java/co/elastic/clients/transport/TransportRetryStatusTest.java	New integration tests validating status-based retries via real low-level clients.
java-client/src/test/java/co/elastic/clients/transport/http/RetryingHttpClientTest.java	New unit tests for retry classification and retry/cancellation behavior.
java-client/src/test/java/co/elastic/clients/transport/ElasticsearchTransportRetryTest.java	New tests validating transport-level routing (client-level vs per-request retry config).
java-client/src/test/java/co/elastic/clients/transport/ElasticsearchTransportConfigTest.java	Adds coverage for the new builder shortcut wiring retry config into transport options.
java-client/src/main/java/co/elastic/clients/transport/TransportOptions.java	Adds `retryConfig()` default + builder hooks to carry retry config through request options.
java-client/src/main/java/co/elastic/clients/transport/RetryConfig.java	New retry configuration type (backoff + retryable statuses/exceptions).
java-client/src/main/java/co/elastic/clients/transport/rest5_client/Rest5ClientOptions.java	Persists/copies retry config into rest5 transport options.
java-client/src/main/java/co/elastic/clients/transport/rest5_client/Rest5ClientHttpClient.java	Exposes status codes from rest5 `ResponseException` for retry classification.
java-client/src/main/java/co/elastic/clients/transport/rest_client/RestClientOptions.java	Persists/copies retry config into legacy rest transport options.
java-client/src/main/java/co/elastic/clients/transport/rest_client/RestClientHttpClient.java	Exposes status codes from legacy `ResponseException` for retry classification.
java-client/src/main/java/co/elastic/clients/transport/http/TransportHttpClient.java	Adds `responseStatusCode(Throwable)` hook for wrapper-agnostic status extraction.
java-client/src/main/java/co/elastic/clients/transport/http/RetryingHttpClient.java	New retrying wrapper implementation (sync/async + backoff scheduling + cancellation).
java-client/src/main/java/co/elastic/clients/transport/ElasticsearchTransportConfig.java	Adds builder shortcuts to configure retries via the top-level client builder.
java-client/src/main/java/co/elastic/clients/transport/ElasticsearchTransportBase.java	Routes requests through a shared retry wrapper when retries are enabled.
java-client/src/main/java/co/elastic/clients/transport/DefaultTransportOptions.java	Adds retry config storage and builder support in the default options implementation.
java-client/src/main/java/co/elastic/clients/transport/BackoffPolicy.java	Fixes minor doc typos.

Comments suppressed due to low confidence (2)

java-client/src/main/java/co/elastic/clients/transport/http/RetryingHttpClient.java:242

isRetryableFailure only checks err and one getCause() level for a status-carrying exception. If the low-level client's ResponseException is wrapped more deeply (common with async frameworks), the retry decision can fall back to exception-type matching and incorrectly retry / not retry. Consider walking the full cause chain when extracting a status code.

        Integer status = delegate.responseStatusCode(err);
        if (status == null && err.getCause() != null) {
            status = delegate.responseStatusCode(err.getCause());
        }
        if (status != null) {

java-client/src/main/java/co/elastic/clients/transport/http/RetryingHttpClient.java:250

RetryConfig docs say wrapped exceptions are considered, but isRetryableException only checks the exception itself and a single cause. This can miss retryable causes nested deeper in the chain (e.g., CompletionException -> RuntimeException -> IOException). Iterate through the full cause chain until null/self-reference.

    boolean isRetryableException(RetryConfig config, Throwable err) {
        return matchesRetryable(config, err) || matchesRetryable(config, err.getCause());
    }

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

* rewriting global retry, addressing review * refactoring retrying logic * add logs * minimal test refactor * add configurable exception logic * comments * code style * simplify test * single request retry * bugfixes, fetching inner status code * refactor, simplify * better comments * more simplifying comments * fix rebase * address copilot review Co-authored-by: Laura Trotta <153528055+l-trotta@users.noreply.github.com>

l-trotta requested a review from swallez March 3, 2025 17:00

l-trotta mentioned this pull request Apr 29, 2025

BulkIngester retry policies #478

Closed

swallez requested changes Sep 23, 2025

View reviewed changes

l-trotta marked this pull request as draft September 26, 2025 08:29

l-trotta mentioned this pull request Jan 7, 2026

Add configurable single node retry #1120

Closed

l-trotta mentioned this pull request Apr 20, 2026

Configurable Retry Status Codes and Max Retry Count until Node Failover - RestClient #1212

Open

l-trotta force-pushed the transport-level-retry branch from 8012980 to 2fd0bbc Compare June 19, 2026 16:35

l-trotta marked this pull request as ready for review June 19, 2026 16:43

l-trotta added 13 commits July 30, 2026 17:18

rewriting global retry, addressing review

a72eea2

refactoring retrying logic

4b634ae

add logs

78b382d

minimal test refactor

d258cb0

add configurable exception logic

4aacb3d

comments

4e631ca

code style

0658b04

simplify test

872a258

single request retry

9aacaed

bugfixes, fetching inner status code

3a49bf3

refactor, simplify

4ef7c43

better comments

e6dfa5d

more simplifying comments

ba8a26b

l-trotta force-pushed the transport-level-retry branch from be599ac to ba8a26b Compare July 30, 2026 15:19

fix rebase

bbf4c23

l-trotta requested a review from Copilot July 30, 2026 15:41

Copilot started reviewing on behalf of l-trotta July 30, 2026 15:41 View session

Copilot AI reviewed Jul 30, 2026

View reviewed changes

Comment thread java-client/src/test/java/co/elastic/clients/transport/TransportRetryStatusTest.java

Comment thread java-client/src/main/java/co/elastic/clients/transport/RetryConfig.java

Comment thread java-client/src/main/java/co/elastic/clients/transport/http/RetryingHttpClient.java Outdated

address copilot review

19db0f5

l-trotta added the backport 9.5 label Jul 30, 2026

l-trotta closed this Jul 30, 2026

l-trotta reopened this Jul 30, 2026

l-trotta merged commit 2cb423b into main Jul 30, 2026
23 checks passed

l-trotta deleted the transport-level-retry branch July 30, 2026 16:09

github-actions Bot mentioned this pull request Jul 30, 2026

[Backport 9.5] Transport level retry #1290

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Transport level retry - #954

Transport level retry#954
l-trotta merged 15 commits into
mainfrom
transport-level-retry

l-trotta commented Mar 3, 2025 •

edited

Loading

Uh oh!

swallez left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

l-trotta commented Mar 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

swallez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

l-trotta commented Mar 3, 2025 •

edited

Loading